Hit-Testing Pictures
As described in "About Hit-Testing Picture Shapes" beginning on page 6-24, QuickDraw GX hit-tests a picture shape by
The criteria you specify includes the depth at which you want to hit-test the picture, and the level of the picture hierarchy at which you want to hit-test.
- hit-testing each item contained in the picture, using the hit-test information in that item's transform object (or overriding transform object, if the item has one) to determine if the item was hit or not
- finding the hit item that corresponds to the depth you specify
- determining the item to return using the level you specify
- providing information about the item
To illustrate picture hit-testing, Listing 6-15 creates a picture hierarchy using the shapes defined in Listing 6-1 on page 6-28 and Listing 6-4 on page 6-33. This example creates a picture shape that contains two items. The first item is a picture of a lawn and a walkway, and the second item is a picture of a house, roof, and door.
Listing 6-15 Creating a picture hierarchy
gxShape groundsPicture, housePicture, entirePicture; gxShape partsOfHouse[4]; gxShape partsOfGrounds[2]; gxShape partsOfEntirePicture[2]; . . . partsOfGrounds[0] = lawnPolygon; partsOfGrounds[1] = walkwayPolygon; groundsPicture = GXNewPicture(2, partsOfGrounds, nil, nil, nil); partsOfHouse[0] = houseRectangle; partsOfHouse[1] = roofPolygon; partsOfHouse[2] = doorRectangle; housePicture = GXNewPicture(3, partsOfHouse, nil, nil, nil); partsOfEntirePicture[0] = groundsPicture; partsOfEntirePicture[1] = housePicture; entirePicture = GXNewPicture(2, partsOfEntirePicture, nil, nil, nil);Figure 6-28 shows the items that make up the grounds picture.
Figure 6-29 shows the items that make up the house picture.
Figure 6-30 shows the entire picture created in Listing 6-15.
Figure 6-30 Picture containing grounds picture and house picture
You hit-test a picture shape using the function
GXHitTestPicture. This function takes as its parameters a reference to the picture to hit-test, the test point, an optional hit-test parameters structure, the level at which to hit-test, and the depth at which to hit-test. The sample code in Listing 6-16 shows how to hit-test the picture from Listing 6-15 using a test point offf(122),ff(110).Listing 6-16 Hit-testing a picture shape
gxPoint testPoint = {ff(122), ff(110)}; gxShape hitShape; long level, depth; . . . hitShape = GXHitTestPicture(entirePicture, &testPoint, nil, level, depth);Figure 6-31 shows the location of the test point.Figure 6-31 Hit-testing the picture of house and grounds
If you specify a depth of 2, the hit shape is the house rectangle. If you specify a level of 1, QuickDraw GX returns information about the house picture that contains the house rectangle. Figure 6-32 depicts this selection process.
Figure 6-32 Hit-testing the picture at depth 2 and level 1
The
GXHitTestPicturefunction returns a reference to the shape that was hit by the test point. In this example, the test point falls above four separate shapes: the door rectangle, the house rectangle, the walkway polygon, and the lawn path. By varying the values of the level and depth parameters, you can control which shape is returned by theGXHitTestPicturefunction.Table 6-1 shows which shape is returned for various choices of level and depth.
At depth 1, the returned shape is the frontmost shape that was hit--in this case, the door rectangle, which is at level 2 in the picture hierarchy. If you specify a depth of 1 and a level of 1, the
GXHitTestPicturefunction returns the picture that contains the door rectangle--in this case the house picture.In a similar manner, depth 2 indicates the house rectangle, depth 3 indicates the walkway polygon, and depth 4 indicates the lawn path.
For information about the
GXHitTestPicturefunction, see page 6-67.
Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help
